<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Evaluator > -->
<div class='chapter'>4. Evaluation</div><p class='cindent'><!-- "evaluation" -->

	The following is a complete description of the actions taken by the
evaluator, given a <font class="italic">form</font> to evaluate.

	If <font class="italic">form</font> is a number, the result is <font class="italic">form</font>.

	If <font class="italic">form</font> is a string, the result is <font class="italic">form</font>.

	If <font class="italic">form</font> is a symbol, the result is the binding
of <font class="italic">form</font>.  If <font class="italic">form</font> is unbound, an error is signalled.

	If <font class="italic">form</font> is not any of the above types, and is not a list,
an error is signalled.

	If <font class="italic">form</font> is a special form, indentified by a distinguished
symbol as its car, it is handled accordingly; each special form works
differently.  All of them are documented in this manual.

	If <font class="italic">form</font> is not a special form, it calls for the <font class="italic">application</font>
of a function to <font class="italic">arguments</font>.  The <font class="italic">car</font> of the form is a function or
the name of a function.  The <font class="italic">cdr</font> of the form is a list of forms which
are evaluated to produce arguments, which are fed to the function.  Whatever
results the function <font class="italic">returns</font> is the value of the original <font class="italic">form</font>.

<!-- Someone should do this but I don't want to do it right now. -->
[Here there should be the rest of the moby description of evaluation and application,
particularly multiple values.  Explain the term "variables", also a very
brief bit about locals and specials (fluids and lexicals??).
The nature of functions should be revealed;
including compiled-code, interpreted-code, arrays, stack-groups, closures,
symbols.  Discuss macros.
Talk about function-calling in compiled code, how this is essentially
identical to the <font class="lisp">apply</font> function, and no need for <font class="lisp">(sstatus uuolinks)</font>
and the like.]

<div class='section'>4.1 Functions and Special Forms</div>
<div class='defun'><font class='exdent'><font class='funcname'>eval <font class='italic' color='purple'>x</font></font></font><br>
<font class="lisp">(eval <font class="italic">x</font>)</font> evaluates <font class="italic">x</font>, and returns the result.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq x 43 foo 'bar)
(eval (list 'cons x 'foo))
    =&gt; (43 . bar)
</pre>
	It is unusual to explicitly call <font class="lisp">eval</font>, since usually
evaluation is done implicitly.  If you are writing a simple Lisp program and
explicitly calling <font class="lisp">eval</font>, you are probably doing something wrong.
<font class="lisp">eval</font> is primarily useful in programs which deal with Lisp itself,
rather than programs about knowledge or mathematics or games.
	Also, if you are only interested in getting at the value of a
symbol (that is, the contents of the symbol's value cell), then you
should use the primitive function <font class="lisp">symeval</font>.
'findex "symeval"
	Note: the actual name of the compiled code for <font class="lisp">eval</font> is "<font class="lisp">si:*eval</font>";
this is because use of the <font class="italic">evalhook</font> feature binds the function cell of <font class="lisp">eval</font>.
If you don't understand this, you can safely ignore it.
<p class='cindent'><!-- "evalhook" -->
'findex "evalhook"
	Note: unlike Maclisp, <font class="lisp">eval</font> never takes a second argument; there
are no "binding context pointers" in Lisp Machine Lisp.
They are replaced by Closures (see (closure)).
</div>

<div class='defun'><font class='exdent'><font class='funcname'>apply <font class='italic' color='purple'>fn arglist</font></font></font><br>
<font class="lisp">(apply <font class="italic">fn arglist</font>)</font> applies the function <font class="italic">fn</font> to the list of
arguments <font class="italic">arglist</font>.  <font class="italic">arglist</font> should be a list; <font class="italic">fn</font> can be a
compiled-code object, or a "lambda expression", i.e., a list whose <font class="lisp">car</font>
is the symbol <font class="lisp">lambda</font>, or a symbol, in which case its definition (the contents
of its function cell) is used.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(setq f '+) (apply f '(1 2)) =&gt; 3
(setq f '-) (apply f '(1 2)) =&gt; -1
(apply 'cons '((+ 2 3) 4)) =&gt;
		((+ 2 3) . 4)	<font class="italic">not</font> (5 . 4)
</pre>
	Of course, <font class="italic">arglist</font> may be <font class="lisp">nil</font>.
	Note: unlike Maclisp, <font class="lisp">apply</font> never takes a third argument; there
are no "binding context pointers" in Lisp Machine Lisp.

	Compare <font class="lisp">apply</font> with <font class="lisp">funcall</font> and <font class="lisp">eval</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>funcall <font class='italic' color='purple'>f &rest args</font></font></font><br>
<font class="lisp">(funcall <font class="italic">f a1 a2 ... an</font>)</font> applies the function <font class="italic">f</font> to the arguments
<font class="italic">a1, a2, ..., an</font>.
<font class="lisp">f</font> may not
be a special form nor a macro; this would not be meaningful.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(cons 1 2) =&gt; (1 . 2)
(setq cons 'plus)
(funcall cons 1 2) =&gt; 3
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>lexpr-funcall <font class='italic' color='purple'>f &rest args</font></font></font><br>
<font class="lisp">lexpr-funcall</font> is like a cross between <font class="lisp">apply</font> and <font class="lisp">funcall</font>.
<font class="lisp">(lexpr-funcall <font class="italic">f a1 a2 ... an list</font>)</font> applies the function <font class="italic">f</font>
to the arguments <font class="italic">a1</font> through <font class="italic">an</font> followed by the elements of
<font class="italic">list</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(lexpr-funcall 'plus 1 1 1 '(1 1 1)) =&gt; 6

(defun report-error (&rest args)
   (lexpr-funcall (function format) error-output args))
</pre>
</div>

Note:  the Maclisp functions <font class="lisp">subrcall</font>, <font class="lisp">lsubrcall</font>, and <font class="lisp">arraycall</font>
are not needed on the Lisp Machine; <font class="lisp">funcall</font> is just as efficient.
<!-- Are these provided anyway, though? NO. -->
'findex "subrcall"
'findex "lsubrcall"
'findex "arraycall"

<div class="defspec"><font class='exdent'><font class='funcname'>quote</font><font class="italic"> Special Form</font></font><br>
<p class='cindent'><!-- "quote" -->
<font class="lisp">(quote <font class="italic">x</font>)</font> simply returns <font class="italic">x</font>.  It is useful because it takes the
argument <font class="italic">quoted</font>, so that it is not evaluated by <font class="lisp">eval</font>.  <font class="lisp">quote</font> is used
to include constants in a form.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(quote x) =&gt; x
(setq x (quote (some list)))   x =&gt; (some list)
</pre>
	Since <font class="lisp">quote</font> is so useful but somewhat cumbersome to type, the reader normally
converts any form preceded by a single quote (<font class="lisp">'</font>) character into a <font class="lisp">quote</font> form.
<pre class="lisp">
<font class="main">For example,</font>
(setq x '(some list))
<font class="main">is converted by read into</font>
(setq x (quote (some list)))
</pre>
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>function</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">(function <font class="italic">x</font>)</font> is similar to <font class="lisp">quote</font>, except that it implies
to the compiler that <font class="italic">x</font> is a function.  In the interpreter, if <font class="italic">x</font> is a symbol
<font class="lisp">(function <font class="italic">x</font>)</font> returns <font class="italic">x</font>'s definition;
otherwise <font class="italic">x</font> itself is returned.
Because of this, using <font class="lisp">function</font> rules out the possibility of later
changing the function definition of <font class="italic">x</font>, including tracing it.  Care is required!
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>comment</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">comment</font> ignores its form and returns the symbol <font class="lisp">comment</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(defun foo (x)
    (cond ((null x) 0)
          (t (comment x has something in it)
             (1+ (foo (cdr x))))))
</pre>
	Usually it is preferable to comment code using the
semicolon-macro feature of the standard input syntax.  This allows the
user to add comments to his code which are ignored by the lisp reader. 
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(defun foo (x)
    (cond ((null x) 0)
          (t (1+ (foo (cdr x))))     ;x has something in it
      ))
</pre>

A problem with such comments is that they are discarded when the S-expression
is read into lisp.  If the function is read into Lisp, modified, and printed
out again, the comment will be lost.  However, this style of operation is hardly
ever used; usually the source of a function is kept in an editor buffer and
any changes are made to the buffer, rather than the actual list structure
of the function.  Thus, this is not a real problem.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='@define'>@define</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>	This macro turns into <font class="lisp">nil</font>.  It exists for the sake of the
@ listing generation program, which uses it to declare names of special forms
which define objects (such as functions) which @ should cross-reference.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>progn</font><font class="italic"> Special Form</font></font><br>
A progn-form looks like <font class="lisp">(progn <font class="italic">form1 form2 ...</font>)</font>.
The <font class="italic">forms</font> are evaluated in order from left to right and the value
of the last one is the result of the progn. 
<font class="lisp">progn</font> is the primitive control structure construct for "compound
statements".  Although lambda-expressions, cond-forms, do-forms, and
many other control structure forms use <font class="lisp">progn</font> implicitly, that is,
they allow multiple forms in their bodies, there are occasions when
one needs to evaluate a number of forms for their side-effects and
make them appear to be a single form.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(foo (cdr a)
     (progn (setq b (extract frob))
	    (car b))
     (cadr b))
</pre>
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>prog1</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">prog1</font> is similar to <font class="lisp">progn</font>, but it returns the value of its <font class="italic">first</font> form.
It is most commonly used to evaluate an expression with side effects, and return
a value which must be computed <font class="italic">before</font> the side effects happen.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq x (prog1 y (setq y x)))
</pre>
which interchanges the values of the variables <font class="italic">x</font> and <font class="italic">y</font>.

<font class="lisp">prog1</font> could have been defined as:
<pre class="lisp">
(defun prog1 (&rest values)
    (car values))
</pre>
It is actually implemented as a macro which expands into a <font class="lisp">prog2</font>.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>prog2</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">prog2</font> is similar to <font class="lisp">progn</font> and <font class="lisp">prog1</font>,
but it returns its <font class="italic">second</font> argument.
It is included largely for Maclisp compatibility.  It has two purposes: to evaluate
two forms sequentially, which can be done more generally with <font class="lisp">progn</font>, or
to do what <font class="lisp">prog1</font> is used for (c.f. <font class="lisp">prog1</font> above).
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>let</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">let</font> is used to bind some variables for some objects.
A <font class="lisp">let</font> form looks like
<pre class="lisp">
(let ((<font class="italic">var1</font> <font class="italic">vform1</font>)
      (<font class="italic">var2</font> <font class="italic">vform2</font>)
      ...)
  <font class="italic">bform1</font>
  <font class="italic">bform2</font>
  ...)
</pre>
When this form is evaluated, first the <font class="italic">vform</font>s are evaluated.
Then the <font class="italic">var</font>s are bound to the values returned by the
corresponding  <font class="italic">vform</font>s.  Finally, the <font class="italic">bform</font>s are evaluated sequentially
and the result of the last one returned.

<font class="lisp">let</font> is implemented as a macro which expands into a lambda-combination;
however, it is preferable
to use <font class="lisp">let</font> rather than <font class="lisp">lambda</font> because the variables and the corresponding forms
appear textually close to each other, which increases readability
of the program.
</div>

See also <font class="lisp">let-globally</font>, (let-globally-fun).

<div class="defspec"><font class='exdent'><font class='funcname'>progv</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">progv</font> is a special form to provide the user with extra control
over lambda-binding.  It binds a list of symbols to a list of values,
and then evaluates some forms.  The lists of symbols and values
are computed quantities; this is what makes <font class="lisp">progv</font> different from
<font class="lisp">lambda</font>, <font class="lisp">let</font>, <font class="lisp">prog</font>, and <font class="lisp">do</font>.

<pre class="lisp">
(progv <font class="italic">symbol-list value-list form1 form2 </font>... )
</pre>
first evaluates <font class="italic">symbol-list</font> and <font class="italic">value-list</font>.  Then the symbols
are bound to the values.  In compiled code the symbols must be <font class="italic">special</font>,
since the compiler has no way of knowing what symbols might appear in the
<font class="italic">symbol-list</font>.  If too few values are supplied, the remaining symbols
are bound to <font class="lisp">nil</font>.  If too many values are supplied, the
excess values are ignored.

After the symbols have been bound to the values, the <font class="italic">form</font>s are
evaluated, and finally the symbols' bindings are undone.
The result returned is the value of the last form.  Note that the
"body" of a <font class="lisp">progv</font> is similar to that of <font class="lisp">progn</font>, not that of <font class="lisp">prog</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a 'foo b 'bar)

(progv (list a b 'b) (list b) (list a b foo bar))
    =&gt; (foo nil bar nil)
</pre>
During the evaluation of the body of this <font class="lisp">progv</font>, <font class="lisp">foo</font>
is bound to <font class="lisp">bar</font>, <font class="lisp">bar</font> is bound to <font class="lisp">nil</font>, <font class="lisp">b</font> is
bound to <font class="lisp">nil</font>, and <font class="lisp">a</font> remains bound to <font class="lisp">foo</font>.
</div>

See also <font class="lisp">bind</font> (see (bind-fun)), which is a
subprimitive which gives you maximal control over binding.

The following three functions (<font class="lisp">arg</font>, <font class="lisp">setarg</font>, and <font class="lisp">listify</font>)
exist only for compatibility with Maclisp <font class="italic">lexprs</font>.
<p class='cindent'><!-- "lexpr" -->

<div class='defun'><font class='exdent'><font class='funcname'>arg <font class='italic' color='purple'>x</font></font></font><br>
<font class="lisp">(arg nil)</font>, when evaluated during the application of
a lexpr, gives the number of arguments supplied to that
lexpr.
This is primarily a debugging aid, since lexprs also receive their number of arguments
as the value of their <font class="lisp">lambda</font>-variable.

<font class="lisp">(arg <font class="italic">i</font>)</font>, when evaluated during the application of a lexpr, gives the value of the
<font class="italic">i</font>'th argument to the lexpr.  <font class="italic">i</font> must be a fixnum in this case. It is an error if <font class="italic">i</font> is less than 1 or greater than the number
of arguments supplied to the lexpr.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(defun foo nargs            ;<font class="main">define a lexpr </font>foo.
    (print (arg 2))         ;<font class="main">print the second argument.</font>
    (+ (arg 1)              ;<font class="main">return the sum of the first</font>
       (arg (- nargs 1))))  ;<font class="main">and next to last arguments.</font>
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>setarg <font class='italic' color='purple'>i x</font></font></font><br>
<font class="lisp">setarg</font> is used only during the application of a lexpr.
<font class="lisp">(setarg <font class="italic">i x</font>)</font> sets the
lexpr's <font class="italic">i</font>'th argument to <font class="italic">x</font>.
<font class="italic">i</font> must be greater than zero
and not greater than the number of arguments passed to the lexpr.
After <font class="lisp">(setarg <font class="italic">i x</font>)</font> has been done, <font class="lisp">(arg <font class="italic">i</font>)</font> will return <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>listify <font class='italic' color='purple'>n</font></font></font><br>
<font class="lisp">(listify <font class="italic">n</font>)</font> manufactures a list of <font class="italic">n</font> of the
arguments of a lexpr.  With a positive argument <font class="italic">n</font>, it returns a
list of the first <font class="italic">n</font> arguments of the lexpr.  With a negative
argument <font class="italic">n</font>, it returns a list of the last <font class="lisp">(abs <font class="italic">n</font>)</font>
arguments of the lexpr.  Basically, it works as if defined as follows: 
<pre class="lisp">
    (defun listify (n)
         (cond ((minusp n)
                (listify1 (arg nil) (+ (arg nil) n 1)))
               (t
                (listify1 n 1)) ))

    (defun listify1 (n m)      ;<font class="main"> auxiliary function.</font>
         (do ((i n (1- i))
              (result nil (cons (arg i) result)))
             ((&lt; i m) result) ))
</pre>
</div>

<div class='section'>4.2 Functions and Special Forms</div>
The Lisp machine includes a facility by which the evaluation of a form
can produce more than one value.  When a function needs to return more
than one result to its caller, multiple values are a cleaner way of doing
this than returning a list of the values or <font class="lisp">setq</font>'ing special variables
to the extra values.

In the normal case, multiple values are not used.  Special syntax is
required both to <font class="italic">produce</font> multiple values and to <font class="italic">receive</font> them.
If the caller does not receive multiple values, the first of the
multiple values will be received as the ordinary value.

The primitive for producing multiple values is <font class="lisp">return</font>, which when
given more than one argument returns all its arguments as the values of
the <font class="lisp">prog</font> or <font class="lisp">do</font> from which it is returning.  The variant
<font class="lisp">return-from</font> also can produce multiple values.  Many system functions
produce multiple values, but they all do it via the <font class="lisp">return</font> primitive.
<!-- This could be phrased better. ******* -->

The special forms for receiving multiple values are <font class="lisp">multiple-value</font>,
<font class="lisp">multiple-value-list</font>, and <font class="lisp">multiple-value-bind</font>.  These include
a form and an indication of where to put the values returned by that form.

<div class="defspec"><font class='exdent'><font class='funcname'>multiple-value</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">(multiple-value <font class="italic">var-list</font> <font class="italic">form</font>)</font> is a special
form used for calling a function which
is expected to return more than one value.
<p class='cindent'><!-- "multiple value" -->
<p class='cindent'><!-- returning multiple values -->
<font class="italic">var-list</font> should be a list of variables.
<font class="italic">form</font> is evaluated, and the variables in <font class="italic">var-list</font>
will be <font class="italic">set</font> (not lambda-bound) to the values returned by <font class="italic">form</font>.  If more values
are returned than there are variables in <font class="italic">var-list</font>, then the extra values
are ignored.  If there are more variables than values returned,
extra values of <font class="lisp">nil</font> are supplied.  It is allowed to have <font class="lisp">nil</font>
in the <font class="italic">var-list</font>, which means that the corresponding value is to be
ignored (you can't use <font class="lisp">nil</font> as a variable.)
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(multiple-value (symbol already-there-p)
	(intern "goo"))
</pre>
<font class="lisp">intern</font> returns a second value, which is <font class="lisp">t</font> if the symbol returned as the
first value was already on the obarray, or else <font class="lisp">nil</font> if it just put it there.
So if the symbol <font class="lisp">goo</font> was already on the obarray, the variable <font class="lisp">already-there-p</font>
will be set to <font class="lisp">t</font>, else it will be set to <font class="lisp">nil</font>.

<font class="lisp">multiple-value</font> is usually used for effect rather than for value, however
its value is defined to be the first of the values returned by <font class="italic">form</font>.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>multiple-value-bind</font><font class="italic"> Special Form</font></font><br>
This is similar to <font class="lisp">multiple-value</font>, but locally binds the variables which
receive the values, rather than <font class="lisp">setq</font>ing them.  The form looks like:
<pre class="lisp">
(multiple-value-bind (<font class="italic">var1 var2...</font>)
     (<font class="italic">function</font> <font class="italic">args...</font>)
  <font class="italic">body...</font>)
</pre>
The scope of the binding of <font class="italic">var1</font>, <font class="italic">var2</font>, etc. is <font class="italic">body</font>; they are
not bound until after the function call.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>multiple-value-list</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">(multiple-value-list <font class="italic">form</font>)</font> evaluates <font class="italic">form</font>, and returns a list of
the values it returned.  This is useful for when you don't know how many values
to expect.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(setq a (multiple-value-list (intern "goo")))
a =&gt; (goo nil #&lt;Package User&gt;)
</pre>
This is similar to the example of <font class="lisp">multiple-value</font> above; <font class="lisp">a</font> will be set
to a list of three elements, the three values returned by <font class="lisp">intern</font>.
The first is the newly interned symbol <font class="lisp">goo</font>, the second is 
<font class="lisp">nil</font> to indicate that it is newly-interned, and the third is
the package on which it was interned.
</div>

Due to the syntactic structure of Lisp, it is often the case that the value
of a certain form is the value of a sub-form of it.  For example, the
value of a <font class="lisp">cond</font> is the value of the last form in the selected clause.
In most such cases, if the sub-form produces multiple values, the original
form will also produce all of those values.  This <font class="italic">passing-back</font> of
multiple values of course has no effect unless eventually one of the
special forms for receiving multiple values is reached.
The exact rule governing passing-back of multiple values is as follows:

If <font class="italic">X</font> is a form, and <font class="italic">Y</font> is a sub-form of <font class="italic">X</font>, then if the value
of <font class="italic">Y</font> is unconditionally returned as the value of <font class="italic">X</font>, with no
intervening computation, then all the multiple values returned by <font class="italic">Y</font>
are returned by <font class="italic">X</font>.  In all other cases, multiple values or only
single values may be returned at the discretion of the implementation;
users should not depend on this.  The reason we don't guarantee
non-transmission of multiple values is because such a guarantee would
not be very useful and the efficiency cost of enforcing it would be
high.  Even <font class="lisp">setq</font>'ing a variable to the result of a form, then
returning the value of that variable might be made to pass multiple
values by an optimizing compiler which realized that the <font class="lisp">setq</font>ing of
the variable was unnecessary.

Note that use of a form as an argument to a function never passes-back
multiple values.  We choose not to generate several separate arguments
from the several values, because this would make the source code
obscure; it would not be syntactically obvious that a single form does
not coorrespond to a single argument.  Instead the first value of a
form is used as the argument and the remaining values are discarded.
Passing-back of multiple values happens only with special forms.
For clarity, the interaction of several common special forms with
multiple values is described.  This can all be deduced from the rule
given above.

The body of a <font class="lisp">defun</font> or a <font class="lisp">lambda</font>, and variations such as the
body of a function, the body of a <font class="lisp">let</font>, etc. pass back multiple
values from the last form in the body.

<font class="lisp">eval</font>, <font class="lisp">apply</font>, <font class="lisp">funcall</font>, <font class="lisp">lexpr-funcall</font>, and <font class="lisp">&lt;-</font>
pass back multiple values from the function called.

<font class="lisp">progn</font> passes back multiple values from its last form.
<font class="lisp">progv</font> does so also.
<font class="lisp">prog1</font> and <font class="lisp">prog2</font> however do not pass back multiple values.

<font class="lisp">and</font> and <font class="lisp">or</font> pass back multiple values from their last form,
but not from previous forms since the return is conditional.

<font class="lisp">cond</font> passes back multiple values from the last form in the
selected clause, but not if the clause is only one long (i.e. the
returned value is the value of the predicate) since the return is
conditional.  This applies even to the last clause where the return
is not really conditional (the implementation is allowed to pass
or not to pass multiple values in this case).

The variants of <font class="lisp">cond</font>, <font class="lisp">if</font>, <font class="lisp">select</font>, <font class="lisp">selectq</font>, and
<font class="lisp">dispatch</font> pass back multiple values.

<font class="lisp">prog</font> passes back the number of values given as arguments to
the <font class="lisp">return</font> that returns from it.  <font class="lisp">(return <font class="italic">form</font>)</font>
may return 1 value or may return all the values of <font class="italic">form</font>; as always
the implementation is not constrained not to return extra values.
<font class="lisp">(multiple-value-return <font class="italic">form</font>)</font> returns from a <font class="lisp">prog</font>,
passing back all the values of <font class="italic">form</font>.

<font class="lisp">do</font> behaves like <font class="lisp">prog</font> with respect to <font class="lisp">return</font>.
All the values of the last <font class="italic">exit-form</font> are returned.
[This is the "right" thing unless you think of the implementation
in terms of <font class="lisp">return</font>; what should we do?] *******

<font class="lisp">unwind-protect</font> does <font class="italic">not</font> pass back multiple values.
It clearly should, however this is currently difficult to implement.
This should be fixed later. *******

<div class='section'>4.3 Evalhook</div>
.defvar evalhook
If the value of <font class="lisp">evalhook</font> is non-<font class="lisp">nil</font>, then special things
happen in the evaluator.  When a form (even an atom) is to be evaluated,
<font class="lisp">evalhook</font> is bound to <font class="lisp">nil</font> and the function which
was <font class="lisp">evalhook</font>'s value is applied to one argument--the form that was trying
to be evaluated.  The value it returns is then returned from the evaluator.
This feature is used by the <font class="lisp">step</font> program (see (step-fun)).
.end_defvar

<font class="lisp">evalhook</font> is bound to <font class="lisp">nil</font> by <font class="lisp">break</font> and by
the error handler,
and <font class="lisp">setq</font>'ed
to <font class="lisp">nil</font> by errors that go back to top level and print <font class="lisp">*</font>.
This provides the ability to escape from this mode if something bad
happens.

In order not to impair the efficiency of the Lisp interpreter,
several restrictions are imposed on <font class="lisp">evalhook</font>.
It only applies to evaluation -- whether in a read-eval-print loop,
internally in evaluating arguments in forms, or by explicit use
of the function <font class="lisp">eval</font>.  It <font class="italic">does not</font> have any effect
on compiled function references, on use of the function <font class="lisp">apply</font>,
or on the "mapping" functions.
(On the Lisp Machine, as opposed to Maclisp, it is not
necessary to do <font class="lisp">(*rset t)</font> nor <font class="lisp">(sstatus evalhook t)</font>.)
<!-- This is from the Maclisp manual, in case we ever support this feature. -->
<!-- Also, as a special case, the array reference which is the first -->
<!-- argument to 3store* is never seen by the 3evalhook* function; -->
<!-- however, the subexpressions of the array reference (the indices) will -->
<!-- be seen.  (This special treatment avoids a problem with the way 3store* -->
<!-- works.) -->
(Also, Maclisp's special-case check for <font class="lisp">store</font> is not implemented.)

<div class='defun'><font class='exdent'><font class='funcname'>evalhook <font class='italic' color='purple'>form hook</font></font></font><br>
<font class="lisp">evalhook</font> is a function which helps
exploit the <font class="lisp">evalhook</font> feature.  The <font class="italic">form</font> is evaluated
with <font class="lisp">evalhook</font> lambda-bound to the functional form <font class="lisp">hook</font>.
The checking of <font class="lisp">evalhook</font> is bypassed in the evaluation
of <font class="italic">form</font> itself, but not in any subsidiary evaluations,
for instance of arguments in the <font class="italic">form</font>.
This is like a "one-instruction proceed" in a machine-language
debugger.  
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
<font class="main">;; This function evaluates a form while printing debugging information.</font>
(defun hook (x)
   (terpri)
   (evalhook x 'hook-function))

<font class="main">;; Notice how this function calls <font class="lisp">evalhook</font> to evaluate the form <font class="lisp">f</font>,</font>
<font class="main">;; so as to hook the sub-forms.</font>
(defun hook-function (f)
   (let ((v (evalhook f 'hook-function)))
     (format t "form: ~s~%value: ~s~%" f v)
     v))
</pre>

The following output might be seen from <font class="lisp">(hook '(cons (car '(a . b)) 'c))</font>:
<pre class="lisp">
form: (cons (car (quote (a . b))) (quote c))
form: (car (quote (a . b)))
form: (quote (a . b))
value: (a . b)
value: a
form: (quote c)
value: c
value: (a . c)

(a . c)
</pre>
</div>
.eof
</body>
</html>

